<HTML>
<BODY BGCOLOR=white>
<PRE>
<!-- Manpage converted by man2html 3.0.1 -->
NAME
     lCreateList,  lFreeList,  lCopyList,  lAddList,  lPSortList,
     lDumpList,  lUndumpList, lWriteList, lWriteListTo, lGetList-
     Name, lGetListDescr, lGetNumberOfElem

     generic list manipulation and information functions

SYNOPSIS
     #include "cull.h"

     lList* lCreateList( char *listname, lDescr *descriptor );

     lList* lCreateElemList( char *listname, lDescr  *descriptor,
     int n );

     lList* lFreeList( lList *list );

     lList* lCopyList( char *listname, lList *list );

     void lAddList( lList *list1, lList *list2 );

     int lPSortList( lList *list, char *orderstring, ... );

     int lDumpList( FILE *file, lList *list, int indent );

     lList* lUndumpList(
          FILE *file,
          char *newname,
          lDescr *descriptor
     );

     void lWriteList( lList *list );

     void lWriteListTo( lList *list, FILE *fp );

     char* lGetListName( lList *list );

     lDescr* lGetListDescr( lList *list );

     int lGetNumberOfElem( lList *list );

     int lGetNumberOfRemainingElem( lListElem *elem );

DESCRIPTION
     lCreateList
          gets the new name of the list to  be  created  and  its
          descriptor  which  enumerates  the  fields (name,type),
          that a list element will contain.  The memory  for  the
          list  is dynamically created and a pointer to the newly
          created list is returned.  If one of the  arguments  is
          NULL or if the descriptor contains no fields the return
          value of <I>lCreateList</I> is NULL. This is also true for any
          error  that  might  occur.  The list must be freed with
          <I>lFreeList</I> when the list is no longer used (all  associ-
          ated sub-lists and strings are also freed).

     lCreateElemList
          gets the new name of the list to  be  created  and  its
          descriptor  which  enumerates  the  fields (name,type),
          that a list element will contain.  The  third  argument
          specifies the number of elements that shall be created.
          The memory for the list is dynamically  created  and  a
          pointer  to the newly created list is returned.  If one
          of the arguments is NULL, if the descriptor contains no
          fields  or  if creation of all requested elements fails
          the return value of <I>lCreateElemList</I> is  NULL.  This  is
          also  true  for  any  error that might occur.  The list
          must be freed with <I>lFreeList</I> when the list is no longer
          used  (all  associated  sub-lists  and strings are also
          freed).

     lFreeList
          gets as argument a pointer to a generic  list.  If  the
          list  pointer is NULL the function simply returns, oth-
          erwise the list, all its sub-lists and its strings  are
          freed.

     lCopyList
          copies an existing generic list with all its sub-lists.
          The  required memory is allocated by <I>lCopyList</I> and must
          be released via <I>lFreeList</I> if  the  copied  list  is  no
          longer  used.   The  first argument to lCopyList is the
          name of the copied list,  the  second  argument  is  an
          existing  list.   In  case  of success a pointer to the
          copied list is returned. Otherwise the return value  is
          NULL.

     lAddList
          concatenates two generic lists. The first  argument  is
          the  list which is expanded. The second argument is the
          list that is added to the first list.  The  descriptors
          of  both  lists  have  to be equal. After appending the
          elements of the second list  to  the  first  list,  the
          second list gets destroyed.

     lPSortList
          sorts a given list corresponding to a given sort order.
          The  first  argument  is the generic list to be sorted,
          the second argument is the sort order  string  and  the
          following  variable  argument list specifies the fields
          which act as sorting keys.  lPSortList  returns  -1  in
          case of error, 0 otherwise.
          The sort order string has the following syntax:

               sort order string = %I{+|-} [%I{+|-}...]

          %I  stands  for  the   field   and   +/-   stands   for
          ascending/descending sorting order
          for every percent sign there is one 'fieldname' in  the
          variable argument list, %I stands for the field and +/-
          stands for ascending/descending sorting order.

          The following example may show the usage:

               lPSortList( list, "%I+ %I-", field1, field2 );

     lDumpList
          writes a generic list and all its sub-lists to a  file.
          The  first argument is a FILE pointer, the second argu-
          ment is a generic list pointer and the  third  argument
          is the number of indentation units for the lines in the
          list file (for better readability).

     lUndumpList
          read a dumped list and all its sub-lists  from  a  dump
          file.   The  first  argument is the FILE pointer of the
          dump file. The second argument is the program  internal
          name of the read in list or the name of the list in the
          dump file if NULL is specified. The third  argument  is
          the  descriptor  of the new list or the list descriptor
          stored in the dump file if NULL is  specified.  If  the
          new  list  descriptor  is a subset of the descriptor in
          the dump file the obsolete fields  are  skipped  and  a
          warning  message  is  displayed.  If  additional fields
          occur in the new descriptor they remain unchanged (i.e.
          they  keep  their creation time value).  If <I>lUndumpList</I>
          is successful, a generic list is created and  the  list
          pointer  is  returned.  Otherwise  the  return value is
          NULL.

     lWriteList
          writes a generic list and all its sub-lists if Monitor-
          ing  Level  CULL_LAYER is set to info. The generic list
          pointer is the only  function  argument.  If  the  list
          pointer  is  NULL  the  function displays a warning and
          returns.

     lWriteListTo
          writes a generic list and  all  its  sub-lists  to  the
          stream  connected  with fp. The generic list pointer is
          the first function argument. The second argument is the
          file pointer. If the file pointer is NULL, the function
          behaves as "lWriteList".

     lGetListName
          returns the name of the specified generic list. If  the
          function  argument  is NULL, the string 'No List speci-
          fied' is returned.

     lGetListDescr
          returns the list descriptor of the  specified  list  or
          NULL if a NULL if the argument is NULL.

     lGetNumberOfElem
          gets the number of list elements actually contained  in
          the generic list specified as function argument. If the
          generic list pointer  is  NULL,  -1  is  returned,  the
          number of list elements is returned otherwise.

     lGetNumberOfRemainingElem
          returns the number of list elements  contained  in  the
          remainder of a generic list after a specified list ele-
          ment.

RETURN VALUES
     In case of error the return value is -1 or NULL, otherwise 0
     or a valid pointer to the corresponding struct is returned.

ERRORS
     The following errors may occur. The affected  functions  are
     listed in parentheses.

     LENOLISTNAME
          No list name specified. (<I>lCreateList</I>)

     LEDESCRNULL
          List descriptor is NULL. (<I>lCreateList</I>)

     LEMALLOC
          <B><A HREF="../htmlman3/Malloc.html">Malloc(3)</A></B> failed. (<I>lCreateList</I>, <I>lUndumpList</I>)

     LESTRDUP
          <B><A HREF="../htmlman3/Strdup.html">Strdup(3)</A></B> failed. (<I>lCreateList</I>)

     LECOUNTDESCR
          Counting the descriptor  length  failed.  (<I>lCreateList</I>,
          <I>lAddList</I>, <I>lUndumpList</I>)

     LELISTNULL
          List pointer is NULL. (<I>lFreeList</I>, <I>lCopyList</I>,  <I>lAddList</I>,
          <I>lPSortList</I>,  <I>lWriteList</I>,  <I>lGetListName</I>,  <I>lGetListDescr</I>,
          <I>lGetNumberOfElem</I>, <I>lDumpList</I>)

     LECREATELIST
          Creation of a new list failed. (<I>lCopyList</I>,  <I>lPSortList</I>,
          <I>lUndumpList</I>)

     LEAPPENDELEM
          <I>lAppendElem</I> function failed. (<I>lCopyList</I>, <I>lAddList</I>, <I>lUn-</I>
          <I>dumpList</I>)

     LEDIFFDESCR
          Unequal descriptors specified. (<I>lAddList</I>)

     LEDECHAINELEM
          <I>lDechainElem</I> failed. (<I>lAddList</I>, <I>lPSortList</I>)

     LENOFORMATSTR
          No format string specified. (<I>lPSortList</I>)

     LEPARSESORTORD
          Parsing the sort order format string  failed.  (<I>lPSort-</I>
          <I>List</I>)

     LEGETNROFELEM
          Getting number of list elements failed. (<I>lPSortList</I>)

     LEFILENULL
          File pointer to dump file is NULL. (<I>lDumpList</I>,  <I>lUndum-</I>
          <I>pList</I>)

     LESYNTAX
          A syntax error occurred. (<I>lUndumpList</I>)

     LEFIELDREAD
          Reading a field value failed. (<I>lUndumpList</I>)

     LEFGETDESCR
          <I>lUndumpDescr</I> failed. (<I>lUndumpList</I>)

     LEUNDUMPELEM
          <I>lUndumpElem</I> failed. (<I>lUndumpList</I>)

     LECREATEELEM
          <I>lCreateElem</I> failed. (<I>lUndumpList</I>)

     LECOPYSWITCH
          Copying list element fields failed. (<I>lUndumpList</I>)

SEE ALSO
     <B><A HREF="../htmlman1/sge_intro.html">sge_intro(1)</A></B>, <B><A HREF="../htmlman3/list_intro.html">list_intro(3)</A></B>.

COPYRIGHT
     See <B><A HREF="../htmlman1/sge_intro.html">sge_intro(1)</A></B> for a full statement of rights and  permis-
     sions.





</PRE>
<HR>
<ADDRESS>
Man(1) output converted with
<a href="http://www.oac.uci.edu/indiv/ehood/man2html.html">man2html</a>
</ADDRESS>
</BODY>
</HTML>
